home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / misc / memmgrb3.lha / MemManagerBeta3 / docs / memmanager.autodoc next >
Encoding:
Text File  |  1996-09-23  |  11.7 KB  |  444 lines
  1. TABLE OF CONTENTS
  2.  
  3. memmanager.library/--background--
  4. memmanager.library/ChangeVMemPri
  5. memmanager.library/ChangeVMemType
  6. memmanager.library/ClearVMemHierachy
  7. memmanager.library/CreateVMem
  8. memmanager.library/DefineVMemHierachy
  9. memmanager.library/LockVMem
  10. memmanager.library/Protect
  11. memmanager.library/Publish
  12. memmanager.library/PurgeVMem
  13. memmanager.library/RemoveVMem
  14. memmanager.library/UnlockVMem
  15.  
  16. memmanager.library/--background--          memmanager.library/--background--
  17.  
  18. VERSION
  19.     This is the autodoc for memmanager.library v3.
  20.     If later versions of memmanager.library than v3 are available
  21.     then you need to get the latest version of this file.
  22.  
  23.  
  24. PURPOSE
  25.     MemManager.library provides many things, including
  26.  
  27.     * Virtual Memory
  28.     * Disposable Memory
  29.     * Prioritised Memory
  30.     * Memory Hierachies
  31.     * Protected Memory
  32.     * Resource Tracking
  33.  
  34. LICENSE
  35.     As of v3 MemManager is free. Anybody can use it in their programs.
  36.     Gifts are appreciated however. See the AmigaGuide documentation to learn
  37.     how to contact the author.
  38.  
  39.  
  40. memmanager.library/ChangeVMemPri            memmanager.library/ChangeVMemPri
  41.  
  42.     NAME
  43.     ChangeVMemPri
  44.  
  45.     SYNOPSIS
  46.     ChangeVMemPri( obj , mempri )
  47.                A1    D0
  48.  
  49.     void ChangeVMemPri( APTR , LONG )
  50.  
  51.     FUNCTION
  52.     Change the priority of a memory object. Higher priority objects are
  53.     less likely to be removed from memory than low priority objects.
  54.     
  55.     Often you will call this function if you have finished with an object
  56.     or are soon to need an object. Eg the active document in a text
  57.     editor will have the highest priority.
  58.  
  59.     INPUTS
  60.     obj     - A VMem Object created wih CreateVMem
  61.     mempri  - The new priority for the memory block.
  62.  
  63.     NOTE
  64.     The normal priority for an memory object is 0.
  65.  
  66.     Only raise the priority above 0 for objects you are likely to need
  67.     in the near future.
  68.  
  69.     Use negative priorities for objects you aren't likely to need
  70.     for a while or for unimportant disposable memory.
  71.  
  72.     See the amigaguide documentation for memmanager for tips on what
  73.     priorities to use when.
  74.  
  75.  
  76.     Here is a rough guideline on use of priorities
  77.  
  78.     -96 to -127 - special circumstances
  79.     -64 to -95  - memory that is unimportant (often disposable)
  80.     -32 to -63  - memory very unlikely to be needed soon.
  81.     -1  to -31  - memory not likely to be needed for a while
  82.      0          - default priority (most objects are normally this)
  83.      1  to  31  - memory likely to be needed soon
  84.      32 to  63  - memory currently being used (but not locked)
  85.      64 to  95  - memory that should only be removed from memory
  86.             in extreme circumstances
  87.      96 to  127 - special circumstances
  88.  
  89.  
  90.     For more complex hierachies of object priorities or making some
  91.     objects explicitly inferior to others use CreateVMemHierachy.
  92.  
  93.     SEE ALSO
  94.     CreateVMem, ChangeVMemType, CreateVMemHierachy
  95.  
  96.  
  97. memmanager.library/ChangeVMemType          memmanager.library/ChangeVMemType
  98.  
  99.     NAME
  100.     ChangeVMemType
  101.  
  102.     SYNOPSIS
  103.     ChangeVMemType( obj , vmemflags)
  104.             A1    D0
  105.  
  106.     void ChangeVMemType( APTR , LONG )
  107.  
  108.     FUNCTION
  109.     Changes the type of a VMem object to that specified by the new
  110.     vmemflags. See CreateVMem for a list of vmemflags currently
  111.     supported by memmanager.library.
  112.  
  113.     INPUTS
  114.     obj         - a vmem object, as created by CreateVMem
  115.     vmemflags   - a set of vmemflags, as given to CreateVMem
  116.  
  117.     WARNING
  118.     Objects MUST be locked when you change their priority.
  119.     Not locking objects can cause unpredictable results, such as if
  120.     you changed a diposable object that had been disposed into paged
  121.     memory.
  122.  
  123.     SEE ALSO
  124.     CreateVMem, ChangeVMemPri
  125.  
  126.  
  127. memmanager.library/ClearVMemHierachy    memmanager.library/ClearVMemHierachy
  128.  
  129.     NAME
  130.     ClearVMemHierachy
  131.  
  132.     SYNOPSIS
  133.     ClearVMemHierachy( hierachy )
  134.                A1
  135.  
  136.     void ClearVMemHierachy( APTR )
  137.  
  138.     FUNCTION
  139.     Removes vmem objects from the hierachy system.
  140.  
  141.     INPUTS
  142.     hierachy - a pointer to a null terminated array of vmem object
  143.         pointers (as returned by CreateVMem)
  144.  
  145.     NOTE
  146.     You can pass it the same array of objects you gave to
  147.     DefineVMemHierachy when you placed a list of objects into a
  148.     hierachy, or specify a few objects from a larger hierachy. For
  149.     example you could declare an hierachy of 10 objects and then remove
  150.     four objects from it.
  151.  
  152.     SEE ALSO
  153.     DefineVMemHierachy, CreateVMem
  154.  
  155.  
  156. memmanager.library/CreateVMem                  memmanager.library/CreateVMem
  157.  
  158.     NAME
  159.     CreateVMem
  160.  
  161.     SYNOPSIS
  162.     obj = CreateVMemObject( memsize , memflags , initpri , vmemflags )
  163.     D0                      D0        D1         D2        D3
  164.  
  165.     APTR CreateVMemObject( LONG , LONG , LONG , LONG )
  166.  
  167.     FUNCTION
  168.     Create a vmem object of type specified by the paramaters.
  169.  
  170.     INPUTS
  171.     memsize     - size of memory block in bytes. As given to AllocMem
  172.     memflags    - physical memory flags for the type of memory that
  173.             should hold the object when it is in memory.
  174.             As given to AllocMem
  175.     initpri     - mem object priority (usually 0).
  176.             See ChangeVMemPriority and the MemManager.guide
  177.             developer documentation (included in distribution)
  178.             for more information on chosing a priority.
  179.     vmemflags   - type of vmem. eg paged, disposable etc
  180.  
  181.     RETURN
  182.     A pointer to a vmem object handle. The structure of this handle is
  183.     secret as it is likely to be changed in future versions.
  184.  
  185.     NOTE
  186.     Currently the following vmem flags have been defined
  187.  
  188.     paged - Specifies that the memory can be swapped to disk if memory
  189.         gets low.
  190.     disposable - Specifies that the memory will be disposed of if memory
  191.         gets low.
  192.  
  193.     And not yet implemented
  194.  
  195.     chiptofast - If chip memory is low and there is fast memory free, the
  196.         memory block will be moved to fast mem. Only relent when memflags
  197.         specifies that the memory is chip memory.
  198.  
  199.  
  200.     Note that all memory types are protected and resource tracked. See the
  201.     file MemManager.guide (in the developer archive) for information on
  202.     MemManager Memory Protection and Resource Tracking.
  203.  
  204.  
  205.     Memory objects should be freed when they have been finsihed with using
  206.     RemoveVMem.
  207.  
  208.     SEE ALSO
  209.     RemoveVMem, LockVMem, ChangeVMemType, ChangeVMemPri
  210.  
  211.  
  212. memmanager.library/DefineVMemHierachy   memmanager.library/DefineVMemHierachy
  213.  
  214.     NAME
  215.     DefineVMemHierachy
  216.  
  217.     SYNOPSIS
  218.     DefineVMemHierachy( hierachy )
  219.                 A1
  220.  
  221.     void DefineVMemHierachy( APTR )
  222.  
  223.     FUNCTION
  224.     Create a VMem hierachy containing the objects gievn in the supplied
  225.     array, listed from most important to least important.
  226.  
  227.     VMemHierachies are very useful for telling MemManager that one object
  228.     is more important than another. Objects at the end of the list will
  229.     always be removed from memory before those at the beginning.
  230.  
  231.     INPUTS
  232.     hierachy    - a null terminated array of pointers to vmem handles.
  233.             (as returned by CreateVMem)
  234.  
  235.     NOTE
  236.     To see examples of how VMemHierachies can be useful, see the
  237.     MemManager developer documentation.
  238.  
  239.     Hierachies can be cleared using ClearVMemHierachy.
  240.  
  241.  
  242.     SEE ALSO
  243.     CreateVMem, ClearVMemHierachy
  244.  
  245.  
  246. memmanager.library/LockVMem                      memmanager.library/LockVMem
  247.  
  248.     NAME
  249.     LockVMem
  250.  
  251.     SYNOPSIS
  252.     address = LockVMem( obj )
  253.     D0                  A1
  254.  
  255.     APTR LockVMem( APTR )
  256.  
  257.     FUNCTION
  258.     Locks a vmem object into memory and returns a pointer to it. This
  259.     pointer can then be used just like a pointer to a conventional
  260.     memory block until you release it again with UnLockVMem at which
  261.     point the pointer becomes invalid.
  262.  
  263.     INPUTS
  264.     obj - pointer to a vmemhandle as returned by CreateVMem
  265.  
  266.     RETURN
  267.     A pointer to a memory block that you can then work with.
  268.  
  269.     NOTE
  270.     If a memory block cannot be brought into memory this function will
  271.     return null. There are several reasons why this mights happen:
  272.  
  273.         * The memory block was disposable and has been disposed
  274.  
  275.         * The memory block belonged to a task that has terminated
  276.         and has been disposed of by the resource tracker.
  277.  
  278.         * Due to low memory conditions MemManager was unable to
  279.         reserve memory for the object.
  280.         This could happen if tasks lock to much memory or
  281.         non - memmanager tasks allocate a lot a memory with AllocMem
  282.  
  283.         * Due to a disk error the temporary file could not be retreived.
  284.  
  285.     Try to have locks on as little memory as possible. If yuo are going
  286.     to be locking an object a lot then you should give it a high
  287.     priority.
  288.  
  289.  
  290.     Note that LockVMem also tells the Memory Protection system
  291.     (not implemented at time of writing) that your task is allowed to
  292.     read from that block.
  293.  
  294.  
  295.     WARNING
  296.     You must not give pointers to vmem memory blocks to other tasks (eg
  297.     by sending a message or writing to a file) without Publishing them
  298.     first with Publish.
  299.  
  300.     If you don't do this the Memory Protection will stop the other task
  301.     from accessing your memory block.
  302.  
  303.     It is however ok to pass pointers to vmem handles without using
  304.     Publish and loosing the advantages of memory protection and resource
  305.     tracking.
  306.  
  307.     SEE ALSO
  308.     UnLockVMem, Publish, ChangeVMemPri, CreateVMem
  309.  
  310.  
  311. memmanager.library/Protect                        memmanager.library/Protect
  312.  
  313.     NAME
  314.     Protect
  315.  
  316.     SYNOPSIS
  317.     Protect( obj )
  318.          A1
  319.  
  320.     void Protect( APTR )
  321.  
  322.     FUNCTION
  323.     Turns protection back on for an object which has had it's protection
  324.     turned off with Publish. One call to Protect is required for every
  325.     call to Publish.
  326.  
  327.     INPUTS
  328.     obj - pointer to a vmem handle as returned by CreateVMem
  329.  
  330.     SEE ALSO
  331.     Publish, CreateVMem
  332.  
  333.  
  334. memmanager.library/Publish                        memmanager.library/Publish
  335.  
  336.     NAME
  337.     Publish
  338.  
  339.     SYNOPSIS
  340.     Publish( obj )
  341.          A1
  342.  
  343.     void Publish( APTR )
  344.  
  345.     FUNCTION
  346.     Turn off Memory Protection and Resource Tracking for a memory block
  347.     so that it can be used by other tasks without them having to lock it.
  348.     
  349.     INPUTS
  350.     obj - pointer to a vmem handle as returned by CreateVMem
  351.  
  352.     NOTE
  353.     This function MUST be used before passing a pointer to a memory block
  354.     or the Memory Protection system will stop the task using the memory
  355.     and the Resource tracker may free the memory while other tasks are
  356.     using it.
  357.  
  358.     If you are passing pointers to vmem handles between tasks then you
  359.     do not need to publish the memory blocks.
  360.  
  361.     Protection can be turned back on for a memory block using Protect.
  362.  
  363.     If you are passing pointers into memory blocks to non memmanager
  364.     aware tasks then make sure that you keep the memory object locked
  365.     until you are sure that the other task has finished with it.
  366.  
  367.  
  368.     SEE ALSO
  369.     Protect, LockVMem, UnLockVMem, CreateVMem
  370.  
  371.  
  372. memmanager.library/PurgeVMem                    memmanager.library/PurgeVMem
  373.  
  374.     NAME
  375.     PurgeVMem
  376.  
  377.     SYNOPSIS
  378.     PurgeVMem( memflags )
  379.            D1
  380.  
  381.     void PurgeVMem( LONG )
  382.  
  383.     FUNCTION
  384.     Ask MemManager to remove an object from memory so as to give more
  385.     available memory of the type specified.
  386.  
  387.     INPUTS
  388.     memflags - a set of mem flags, as given to exec.library/AllocMem.
  389.  
  390.     NOTE
  391.     This function is in the library so that the AllocMem patch can call
  392.     it. It is not intended that programmers should use this function
  393.     themselves. There is no reason why you shouldn't call it, but it
  394.     is unlikely that you will want to.
  395.  
  396.  
  397. memmanager.library/RemoveVMem                  memmanager.library/RemoveVMem
  398.  
  399.     NAME
  400.     RemoveVMem
  401.  
  402.     SYNOPSIS
  403.     RemoveVMem( obj )
  404.             A1
  405.  
  406.     void RemoveVMem ( APTR )
  407.  
  408.     FUNCTION
  409.     Removes a vmem item created by CreateVMem from the system. This is
  410.     the vmem equivalent of exec.library/FreeMem. If the vmem block
  411.     was in physical memory then that memory will be freed. if it was
  412.     on disk then the temporary file will be deleted.
  413.  
  414.     INPUTS
  415.     obj - A pointer to a vmem handle as returned by CreateVMem
  416.  
  417.     SEE ALSO
  418.     CreateVMem
  419.  
  420.  
  421. memmanager.library/UnlockVMem                  memmanager.library/UnlockVMem
  422.  
  423.     NAME
  424.     UnlockVMem
  425.  
  426.     SYNOPSIS
  427.     UnlockVMem( obj )
  428.             A1
  429.  
  430.     void UnlockVMem( APTR )
  431.  
  432.     FUNCTION
  433.     Unlocks a vmem object allowing it to be removed from addressable
  434.     memory. One call to UnlockVMem is required for every call to LockVMem
  435.     in order for the vmem object to be unlocked.
  436.  
  437.     INPUTS
  438.     obj - a pointer toa vmem handle as returned by CreateVMem
  439.  
  440.     SEE ALSO
  441.     LockVMem, CreateVMem, Publish, Protect
  442.  
  443.   
  444.